Skip to main content

V3 API Overview

Welcome to the Gausium Open Platform V3 API. V3 is organized around robot data, map resources, tasks and scheduling, temporary tasks, and command operations. It uses consistent JSON requests, a unified response envelope, and an online Try It panel on every endpoint page. This page explains the complete API surface; if you are integrating for the first time, start with the sibling "Quick Start" page.

Compatibility and prerequisites​

Compatibility

OpenAPI V3 endpoints are guaranteed only for AIO 1.6 and later. Before calling an endpoint, make sure the robot is bound to the current developer account and that the required maps, work modes, and task resources are available on the robot.

Before calling a business endpoint:

  1. Create an AccessKey in the Developer Center and obtain its AccessKeyID, AccessKeySecret, ClientID, and ClientSecret.
  2. Use the Authentication endpoints to obtain an OAuth access token and refresh it before it expires.

API surface​

DomainCoverage
AuthenticationGet and refresh OAuth tokens. Both endpoints keep the legacy OAuth URL.
Base InfoList robots and get current status snapshots.
Map DataList robot maps, get map canvases, list charging positions, and list map resources.
Tasks and SchedulingManage Combined Task definitions; query work modes, robot capabilities, and task resources; create, update, delete, and query standard/simple schedules; start or skip temporary tasks.
Command OperationGet command status, list command records, navigate to a charging position, and consult the command type reference.

The left navigation follows these domains. Tasks and Scheduling is a full business domain: it includes task definitions and capability/resource queries as well as standard schedules, simple schedules, and temporary tasks.

Common conventions​

  • Method: except for authentication, every endpoint uses POST with a JSON body and Content-Type: application/json.
  • Path prefix: business endpoints start with /openapi/v3/; Get/Refresh OAuth Token keep /gas/api/v1alpha1/oauth/token.
  • Authentication: send Authorization: Bearer {access_token} on business requests. The authentication endpoints themselves exchange client_id, client_secret, and open_access_key in the request body.
  • Limits: each endpoint page documents request limits, required fields, and resource prerequisites; follow the endpoint page when they differ.
  • Unified response: business endpoints return {code, msg, traceId, data}. code = 0 means success; a non-zero code is a six-digit error code, msg contains the error, and data is usually empty. See V3 Error Codes for the full segment rules and troubleshooting steps.

Authentication and command flow​

For a complete integration, use this sequence:

  1. Obtain an access_token with the AccessKey credentials.
  2. Send Authorization: Bearer {access_token} on every business request.
  3. For commands that are dispatched asynchronously, save the returned requestId.
  4. Use "Get Command Status" or "List Command Records" to confirm delivery and execution. cmdStatus = 6 always returns cmdResultCode = 6880 and cmdResultMessage = success; it only means the command was dispatched successfully and does not mean the robot has finished the action. START_FUSION_TASK also includes taskInstanceId when the provider returns a runtime instance.
  5. When the token expires, use the refresh_token endpoint instead of authorizing again.

Status, maps, and coordinates​

Robot status snapshots are not real-time; the endpoint page documents the expected delay. Runtime fields such as battery, current task, map, and position are returned only when the robot is online. When a robot is offline, these fields can be empty or use the documented defaults. Coordinates can be populated only when localization is available, grid coordinates exist, and map metadata is complete; missing any of these prerequisites must not be interpreted as the robot being at the origin.

Map and task-resource endpoints return map IDs, map UUIDs, regions, paths, positions, and work modes that are consumed by later task or schedule requests. Before creating a Combined Task or schedule, query the task resources in "Capabilities and Resources" and use the returned identifiers in the next request.

Try It online​

Every endpoint page includes a Try It panel:

  • fields are seeded from their example values, with required and fixed fields indicated;
  • editing parameters updates a copyable curl command in real time;
  • requests can be sent directly to inspect the response. If the browser is blocked by CORS, copy the curl command and run it in a terminal;
  • before sending a request to a real robot, verify that the token, robot serial number, map, and resources belong to the same account and environment.

For your first request, open the sibling "Quick Start" page. For field definitions, response examples, or command types, use the matching domain in the left navigation.